21장 만든 것 세상에 올리기 (입문판)

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호)

이 장에서 딱 3가지만 가져가세요. 1. 배포가 무엇이고, 왜 그냥 올리기만 하면 안 되는지 설명한다. 2. Vercel(배포 플랫폼)에 가입하고 깃허브 프로젝트를 가져오는 과정을 따라 한다. 3. Deploy 버튼으로 배포하고, 환경변수를 넣은 뒤 다시 배포(Redeploy)하는 흐름을 따라 한다.

이 장에서 나오는 화면 이름, 플랜 이름, 버튼 위치는 원서/노트 기준 예시입니다. 서비스 화면은 자주 바뀌므로, 최신 모습과 무료 사용량은 공식 문서(Vercel 공식 문서 https://vercel.com/docs)에서 확인하세요.

들어가기 전에

이런 적 있죠? 열심히 만든 음식을 식탁에 차렸는데, 손님은 우리 집 주방까지 들어올 수가 없습니다. 아무리 맛있어도 손님 앞에 가져다 놓지 않으면 한 입도 못 먹습니다.

코드도 똑같습니다. 내 노트북 안에서만 잘 돌아가는 웹사이트는, 친구도 가족도 볼 수가 없습니다. "localhost:3000으로 들어와 봐" 해도 그건 내 컴퓨터에서만 열립니다.

이렇게 내 컴퓨터 안에만 있던 서비스를 누구나 인터넷 주소로 접속할 수 있게 "세상에 내놓는 일"이 바로 배포입니다. 이 장은 그 배포를 Vercel이라는 도구로 따라 하는 방법을 다룹니다.

이 장은 앞에서 만든 결과물을 그대로 씁니다. 20장에서 테스트(Playwright)로 점검을 끝낸 프로젝트가 있다고 보고 시작합니다. 지금 그 프로젝트가 없어도 괜찮습니다. 흐름만 눈으로 따라오면 됩니다.

새 용어 미리 한 줄씩: 배포(Deployment): 내가 만든 서비스를 인터넷에 올려 누구나 접속하게 만드는 일. 가게 문을 열고 간판을 다는 것과 같습니다. Vercel: 깃허브에 올린 코드를 자동으로 인터넷에 올려주는 배포 도구. 짐만 맡기면 알아서 배달까지 해주는 택배 회사 같은 것입니다. 환경변수(Environment Variables): API 키나 데이터베이스 주소처럼 코드에 직접 적기 위험한 비밀값을 따로 보관하는 칸. 현관 비밀번호를 문에 써붙이지 않고 따로 적어두는 것과 같습니다.

21-1 배포가 무엇인지 이해하기

이렇게 막힌 적 있죠?

집에서 케이크를 멋지게 구웠다고 해봅시다. 사진을 찍어 친구한테 보냈더니 친구가 말합니다. "맛있겠다. 그거 어디 가면 먹을 수 있어?"

그런데 그 케이크는 우리 집 식탁 위에만 있습니다. 가게도 없고, 배달도 안 하고, 주소도 없습니다. 친구는 그 케이크를 영원히 못 먹습니다.

내 노트북 안에서만 도는 웹사이트가 딱 이 상태입니다. 나만 볼 수 있고, 남은 아무도 못 들어옵니다.

그게 바로 배포

배포는 내 컴퓨터 안에 있던 서비스를 인터넷에 올려, 누구나 주소로 접속하게 만드는 일입니다. 케이크를 가게에 진열하고 주소를 알려주는 것과 같습니다.

그런데 한 가지 중요한 점이 있습니다. 배포는 "그냥 올리기"가 아닙니다. 가게 문을 열 때 위생도 챙기고, 손님이 몰려도 버티게 준비하고, 불이 나면 어쩔지도 생각하듯이 배포할 때도 보안, 성능, 오류 대응을 함께 챙겨야 합니다.

배포 전에 꼭 짚는 4가지

배포 직전에 아래 네 가지를 눈으로 확인하면 큰 사고를 막습니다.

배포 전 체크리스트
─────────────────────────────────
1) 보안    API 키가 코드에 박혀 있지 않은가?
           .env 파일이 .gitignore에 들어 있는가?
2) 성능    이미지 최적화, 안 쓰는 패키지 제거했는가?
3) 오류    404·500 같은 에러 페이지를 준비했는가?
4) 테스트  20장에서 만든 테스트가 전부 통과했는가?

특히 첫 번째 보안 항목이 제일 무섭습니다. 아래 잘못된 예와 올바른 예를 비교해 봅시다.

잘못된 예 .env 파일(비밀값이 담긴 파일)을 그냥 깃허브에 올림. 그러면 전 세계 사람이 내 API 키를 볼 수 있게 됩니다. 요금 폭탄이나 해킹으로 이어집니다.

올바른 예 .env 파일을 .gitignore에 적어 깃허브에 안 올라가게 막음. 그러면 비밀값은 내 컴퓨터와 Vercel 설정 칸에만 남습니다. 안전합니다.

이럴 때 이렇게 "배포했더니 500 에러가 떠요"라는 상황의 가장 흔한 원인은 환경변수를 Vercel에 안 넣은 것입니다. 이건 21-3에서 다시 자세히 다룹니다.

데이터베이스는 이미 인터넷에 있다

한 가지 헷갈리기 쉬운 점을 짚고 갑니다. 이 책의 예제는 데이터베이스로 Supabase를 씁니다. Supabase는 처음부터 인터넷(클라우드)에 있는 서비스라, 이미 누구나 접속 가능한 상태입니다.

그래서 우리가 따로 배포할 것은 웹사이트(화면) 부분뿐입니다. 데이터베이스는 그대로 두고, 웹사이트만 Vercel에 올리면 됩니다.

새 용어 한 줄: Supabase는 인터넷에 올라가 있는 데이터 저장소 서비스입니다. 회원 정보나 글 같은 데이터를 보관하는 클라우드 창고라고 보면 됩니다.

이 장에서 가져갈 핵심 - 배포 = 내 서비스를 인터넷에 올려 누구나 접속하게 만드는 일. - 그냥 올리기가 아니라 보안·성능·오류 대응까지 챙기는 일. - 데이터베이스(Supabase)는 이미 인터넷에 있으니, 웹사이트만 올리면 됨.

21-2 Vercel 준비하기

이렇게 막힌 적 있죠?

이사할 때 짐을 직접 트럭 빌리고, 운전하고, 옮기고, 정리까지 하려면 하루가 다 갑니다. 그런데 이삿짐센터에 맡기면 어떻게 되죠? 짐만 싸두면 트럭부터 운반, 정리까지 알아서 해줍니다.

배포도 직접 하려면 할 일이 많습니다. 서버 빌리고, 설정하고, 주소 연결하고, 보안 인증서 달고… 초보자에게는 벽처럼 느껴집니다.

이 귀찮은 일을 대신 해주는 이삿짐센터가 바로 Vercel입니다.

그게 바로 Vercel

Vercel은 깃허브에 올린 코드를 자동으로 인터넷에 배포해주는 플랫폼입니다. 코드를 깃허브에 올려두면, Vercel이 그걸 가져가 빌드(완성품으로 포장)하고, 전 세계 사용자가 볼 수 있게 올려줍니다.

새 용어 한 줄: 빌드(Build)는 사람이 쓴 코드를 컴퓨터가 실제로 실행할 수 있는 형태로 포장하는 과정입니다. 재료를 손질해 바로 낼 수 있는 요리로 만드는 단계라고 보면 됩니다.

왜 하필 Vercel을 쓰는지 세 가지로 정리하면: - Next.js를 만든 회사가 운영합니다. 그래서 Next.js 프로젝트와 궁합이 가장 좋습니다. - 무료로 시작할 수 있는 플랜(Hobby 플랜)이 있습니다. 돈 없이도 연습 가능합니다. - 깃허브와 연결해두면, 코드를 올릴 때마다 알아서 다시 배포해줍니다.

새 용어 한 줄: Next.js는 웹사이트를 만들 때 많이 쓰는 도구 모음입니다. 이 책의 예제 프로젝트가 Next.js로 만들어져 있습니다.

Hobby 플랜 — 무료로 시작하는 길

Vercel에는 여러 요금제가 있는데, 처음에는 무료인 Hobby 플랜으로 충분합니다.

새 용어 한 줄: Hobby 플랜은 Vercel의 무료 등급입니다. 개인 연습·포트폴리오용으로 넉넉하게 쓸 수 있습니다.

어떤 경우에 어떤 플랜이 맞는지 비교해 봅시다.

지금 우리는 연습 중이므로 Hobby 플랜을 고르면 됩니다. 무료 사용량의 구체 한도(트래픽·빌드 횟수 등)는 시간에 따라 바뀌므로, 정확한 수치는 Vercel 공식 문서에서 확인하세요.

따라 하기 1 — 회원가입

기본 사용법(안전한 길)부터 갑니다.

1) vercel.com/signup 접속
2) 플랜 종류에서 개인 프로젝트용(Hobby) 선택
3) 이름 입력 후 Continue
4) 깃허브 계정으로 로그인 (추천) 또는 이메일로 가입

깃허브로 로그인하길 추천하는 이유는, 다음 단계에서 깃허브 프로젝트를 바로 가져올 수 있어 편하기 때문입니다.

새 용어 한 줄: 깃허브(GitHub)는 코드를 인터넷에 저장하고 함께 관리하는 서비스입니다. 14장에서 다룬 적이 있습니다.

한 걸음 더 ▸ 여기서 깃허브는 여러 로그인 방법 중 한 예시일 뿐입니다. Vercel은 깃허브 말고도 Google, GitLab, Bitbucket 같은 여러 제공자로 로그인할 수 있어요. 카페 문 앞에 "구글로 들어오기", "깃허브로 들어오기" 같은 여러 출입문이 나란히 있는 것과 같습니다. 어느 문으로 들어와도 같은 카페 안입니다. 다만 이 책의 예제는 코드를 깃허브에 올려 쓰니, 깃허브 문으로 들어오면 다음 단계가 가장 매끄럽습니다.

따라 하기 2 — 깃허브 프로젝트 가져오기 (Import)

가입을 마치면 "Import Git Repository"(깃허브 저장소 가져오기) 화면이 보입니다. 여기서 내 프로젝트를 골라 가져옵니다.

새 용어 한 줄: Import는 깃허브에 있는 내 코드를 Vercel로 데려와 프로젝트로 만드는 일입니다. 창고에 있던 짐을 새 집으로 옮겨오는 것과 같습니다.

1) "Import Git Repository" 화면에서 내 프로젝트 검색
2) 원하는 저장소 옆 [Import] 버튼 클릭

따라 하기 3 — 프로젝트 설정 확인

Import를 누르면 새 프로젝트 설정 화면이 나옵니다. 여기서 한 군데만 눈여겨보면 됩니다. 바로 Framework Preset입니다.

새 용어 한 줄: Framework Preset은 "이 프로젝트가 무엇으로 만들어졌는지" Vercel이 알아맞힌 설정입니다. 보통 자동으로 Next.js라고 인식합니다.

New Project 화면 예시
─────────────────────────────────
Project Name:      k-nomad
Framework Preset:  Next.js   ← 보통 자동으로 잡힘
Root Directory:    ./

> Environment Variables   ← 지금 안 넣어도 됨 (21-3에서)

         [ Deploy ]

여기서 Framework Preset이 Next.js로 잘 잡혔는지만 확인하면 됩니다.

잘못된 예 Framework Preset이 비어 있거나 엉뚱한 값인데 그냥 Deploy를 누름. 그러면 빌드가 실패할 수 있습니다.

올바른 예 자동 인식이 안 됐으면 목록에서 직접 "Next.js"를 골라줌. 그러면 Vercel이 올바른 방법으로 빌드합니다.

이럴 때 이렇게 환경변수(API 키 등)는 지금 안 넣어도 됩니다. 첫 배포를 먼저 해보고, 그다음에 넣는 게 더 쉽습니다. 이건 21-3에서 합니다.

이 절에서 가져갈 핵심 - Vercel은 깃허브 코드를 자동으로 배포해주는 도구. - Hobby 플랜(무료)으로 연습을 시작. - 순서는 가입, Import(프로젝트 가져오기), Framework Preset(Next.js) 확인입니다.

21-3 진짜로 배포하고 다시 배포하기

이렇게 막힌 적 있죠?

택배를 보낼 때를 떠올려 봅시다. 물건을 접수하면 "배송 시작"이라고 뜹니다. 그런데 받는 사람 주소를 안 적으면? 물건이 어디로도 도착하지 못합니다.

배포도 똑같습니다. Deploy 버튼을 누르면 배송이 시작되지만, "주소"에 해당하는 환경변수를 안 넣으면 사이트가 제대로 열리지 않습니다.

이 절에서는 배송 접수(Deploy), 추적(빌드 로그 확인), 주소 입력(환경변수), 재발송(Redeploy)까지 순서대로 한 번에 따라 합니다.

그게 바로 Deploy와 Redeploy

Deploy는 처음으로 사이트를 인터넷에 올리는 일입니다. Redeploy는 설정을 바꾼 뒤, 그 변경을 반영하려고 다시 배포하는 일입니다.

새 용어 한 줄: Redeploy(재배포)는 환경변수 같은 설정을 바꾼 다음 다시 한 번 배포하는 것입니다. 주소를 잘못 적어 다시 보내는 택배 재발송과 같습니다.

따라 하기 4 — Deploy 누르기

[Deploy] 버튼 클릭
  → "Deploying..." 으로 화면이 바뀜
  → Build Logs(빌드 기록)가 실시간으로 흐름
  → 의존성 설치 → 빌드 → 최적화 순서로 진행

새 용어 한 줄: Build Logs는 빌드가 어떻게 진행되는지 한 줄씩 보여주는 기록입니다. 일이 잘 됐는지, 어디서 막혔는지를 알려주는 일지라고 보면 됩니다.

따라 하기 5 — 빌드 결과 확인하기

빌드가 끝나면 성공이거나 실패입니다. 둘 다 대처법이 있습니다.

성공한 경우
  → [Continue to Dashboard] 버튼 클릭
  → 대시보드(프로젝트 관리 화면)로 이동

실패한 경우
  → [Logs] 탭에서 빨간 에러 글씨 확인
  → 그 에러 메시지를 복사
  → 클로드 코드에 붙여넣고 "이 에러 고쳐줘"라고 부탁

새 용어 한 줄: 대시보드(Dashboard)는 내 프로젝트의 상태, 배포 기록, 설정을 모아 보는 메인 화면입니다.

이럴 때 이렇게 빌드가 실패했다고 당황하지 않아도 됩니다. 빨간 에러를 그대로 클로드 코드에 붙여넣으면, 원인과 고치는 방법을 알려줍니다. 앞 장에서 클로드 코드에게 코드를 고쳐달라고 부탁하던 것과 똑같은 방식입니다.

따라 하기 6 — 환경변수 넣기

이제 "받는 사람 주소"에 해당하는 환경변수를 넣을 차례입니다.

Settings → Environment Variables 메뉴로 이동

  Key                              Value
  NEXT_PUBLIC_SUPABASE_URL         https://xxx...
  NEXT_PUBLIC_SUPABASE_ANON_KEY    eyJhb...

  → .env(또는 .env.local) 파일에 있던 모든 KEY=VALUE를 그대로 입력
  → [Save] 버튼으로 저장

여기서 입력하는 값은 내 컴퓨터의 .env 파일에 있던 값과 똑같습니다. .env 파일은 깃허브에 안 올렸기 때문에(21-1의 보안 규칙), Vercel은 이 값을 모릅니다. 그래서 여기에 직접 한 번 더 적어주는 것입니다.

한 걸음 더 ▸ .env 파일에 값이 여러 개라 일일이 치기 번거롭다면, "Import .env" 기능으로 파일째 한 번에 넣을 수도 있습니다. 기본은 하나씩 입력이고, 이건 편의 기능입니다.

잘못된 예 환경변수를 넣지 않고 사이트에 접속함. 그러면 데이터베이스 주소를 모르니 500 에러(서버 오류)가 뜹니다.

올바른 예 .env의 모든 값을 Environment Variables에 넣고 Save함. 그러면 사이트가 데이터베이스와 연결되어 정상 작동합니다.

따라 하기 7 — Redeploy 하기

환경변수를 Save해도, 이미 끝난 배포에는 바로 반영되지 않습니다. 반드시 다시 배포(Redeploy)해야 새 값이 적용됩니다.

[Save]를 누르면 화면 아래에 [Redeploy] 안내 막대가 뜸
  → [Redeploy] 클릭
  → 확인 창에서 다시 [Redeploy] 클릭

만약 [Redeploy] 안내가 사라졌다면 (수동으로 재배포)
  → Deployments 탭 이동
  → ··· (점 세 개) 메뉴 → Create Deployment
  → main 브랜치 선택
  → [Create Deployment] 클릭

새 용어 한 줄: Deployments는 지금까지의 배포 기록이 쌓이는 탭입니다. 여기서 수동으로 새 배포를 시작할 수도 있습니다. 새 용어 한 줄: main 브랜치는 프로젝트의 기본(대표) 코드 줄기입니다. 보통 이걸 골라 배포합니다.

이럴 때 이렇게 "환경변수를 넣었는데도 사이트가 안 고쳐졌어요"의 99%는 Redeploy를 안 한 경우입니다. Save만으로는 부족하고, 꼭 한 번 더 배포해야 한다는 점을 기억하세요.

따라 하기 8 — 사이트 방문하고 점검하기

배포가 끝났으면 실제로 들어가 봅니다.

Overview 탭 → [Visit] 버튼 클릭
  → 배포된 주소: 프로젝트명.vercel.app

들어가서 아래를 하나씩 눌러보며 확인합니다.

사이트 점검 목록
─────────────────────────────────
- 모든 페이지가 잘 열리는가?
- 데이터베이스(Supabase) 연동이 되는가? (글·목록 등이 보이는가)
- 버튼·검색 같은 기능이 작동하는가?
- 휴대폰 화면에서도 모양이 깨지지 않는가? (반응형)

자주 만나는 에러와 해결법

배포 후 흔히 만나는 문제를 표로 모았습니다.

이럴 때 이렇게 어떤 에러든 공통 처방은 비슷합니다. 빨간 에러 메시지를 복사해서 클로드 코드에게 보여주고 "고쳐줘"라고 부탁하면 됩니다. 혼자 끙끙대지 말고 에러 글자를 그대로 넘기는 게 가장 빠릅니다.

이 절에서 가져갈 핵심 - Deploy를 누르면 빌드가 시작되고, Build Logs로 진행을 봄. - 환경변수(.env의 값들)를 Settings에 넣고 Save함. - 환경변수를 바꿨으면 반드시 Redeploy해야 반영됨. - 다 되면 Visit으로 사이트에 들어가 기능을 하나씩 점검함.

한눈에 정리 — 로컬과 배포는 무엇이 다른가

내 컴퓨터에서 돌릴 때와 Vercel에 올렸을 때를 나란히 보면 차이가 또렷해집니다.

그리고 첫 배포(Deploy)와 재배포(Redeploy)의 차이도 정리합니다.

스스로 점검하기

아래 질문에 스스로 답해 보세요. 막히면 해당 절로 돌아가면 됩니다.

질문 1: 배포가 "그냥 코드를 올리는 것"이 아니라면, 무엇을 더 챙겨야 하나요? 힌트: 21-1의 비유 표(위생·손님·대피)를 떠올려 보세요.

질문 2: 환경변수를 Vercel에 넣고 Save만 했는데 사이트가 안 고쳐집니다. 무엇을 빠뜨렸나요? 힌트: "받는 사람 주소를 고친 뒤 택배를 어떻게 한다고 했죠?"

질문 3: 배포가 실패해 빌드가 멈췄습니다. 에러 원인은 어디서 보고, 어떻게 고치면 빠를까요? 힌트: 21-3의 [Logs] 탭과 클로드 코드 활용을 떠올려 보세요.

질문 4: 무료 Hobby 플랜은 어떤 경우에 적합하고, 어떤 경우엔 유료 플랜이 필요할까요? 힌트: 21-2의 플랜 비교 표를 보세요.

다음 장 예고

여기까지 따라왔다면, 내가 만든 서비스를 인터넷에 올려 친구에게 주소를 보낼 수 있게 됐습니다. 다음 장에서는 클로드 코드를 더 강력하게 써주는 바깥 도구들을 하나씩 소개합니다. 지금 몰라도 됩니다.